Inside Macintosh: QuickDraw GX Objects /

Chapter 5 - Ink Objects / Using Ink Objects

Manipulating Ink Object Properties

This section describes how to manipulate the common object properties of ink objects: attributes, owner count, and tag list.

To manipulate the color of an ink, see the section "Getting and Setting an Ink Object's Color" beginning on page 5-42. To manipulate the transfer mode of an ink, see the section "Getting and Setting an Ink Object's Transfer Mode" beginning on page 5-43.

For manipulating an ink object as a whole, see "Creating and Manipulating Ink Objects" beginning on page 5-38.

Getting and Setting an Ink Object's Attributes

You can use the GXGetInkAttributes function to find the attributes of an existing ink object, and the GXSetInkAttributes function to set the attributes of an ink. The following statements return the attributes for the source shape's ink:

gxInkAttribute whatAttributes;
whatAttributes = GXGetInkAttributes(GXGetShapeInk(source));

As an example, to clear the gxSuppressHalftoneInk attribute of an ink referenced by the variable target, you could use the following statement:

GXSetInkAttributes(target, 
            GXGetInkAttributes(target) & ~gxPortAlignDitherInk);

Conversely, to set the gxSuppressHalftoneInk attribute, you could use the following line of code:

GXSetInkAttributes(target, 
            GXGetInkAttributes(target) | gxSuppressHalftoneInk); 

Ink attributes are described in the section "Ink Attributes" beginning on page 5-9. The GXGetInkAttributes function is described on page 5-61. The GXSetInkAttributes function is described on page 5-62.

Manipulating an Ink Object's Owner Count

The owner count of an object indicates the number of current references to that object. In general, QuickDraw GX manages owner counts for you. For example, when you create a new ink object, QuickDraw GX sets the owner count of the new ink to 1. When you assign an existing ink object to a shape, QuickDraw GX increments the ink's owner count, corresponding to the new reference to the ink contained in the shape object.

If you want to manage an ink's owner count directly, or if you want to know whether an ink object is shared, you can use the GXGetInkOwners function to determine the owner count of an ink, and the GXCloneInk and GXDisposeInk functions to change the owner count of an ink. The GXCloneInk function increments the ink's owner count, and the GXDisposeInk function decrements the ink's owner count, freeing the memory used by the ink if the owner count goes to 0.

The GXGetInkOwners function is described on page 5-64.

In the chapter "Style Objects" in this book, the section on manipulating a style object's owner count discusses two common owner-count problems and how to avoid them. The problems are discussed in terms of style objects, but they apply equally well to ink and transform objects. Refer to that discussion if you find that ink objects you create have owner counts that are higher or lower than you expect.

Getting and Setting an Ink Object's Tag References

You can examine the list of references to tag objects currently associated with an ink object using the GXGetInkTags function. Once you create a tag object, you can attach it to an ink object using the GXSetInkTags function. You can attach as many tag objects as you like to an ink object.

Tag objects and the basic functions for manipulating them are described in the chapter "Tag Objects" in this book. That chapter also lists the common tag types defined and reserved by Apple Computer, Inc.

The GXGetInkTags function is described on page 5-65. The GXSetInkTags function is described on page 5-66.